The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / graphx11.zoo / docs / graphx11.txt < prev

Wrap

Text File | 1992-08-06 | 74.5 KB | 1,733 lines

Graphics Library v1.1 ===================== for Lattice C v5.06, Sozobon C v2.0 and Heat & Serve Sozobon C v1.33i ** FREEWARE ** Copyright (c) 1992 by Kenneth W. Hartlen Box 37, Site 6, RR#3, Armdale, Nova Scotia B3L 4J3 Canada Internet address: hartlenk@newton.ccs.tuns.ca August 6, 1992 Turbo C v2.0 is a registered trademark of Borland International, Inc. Copyright (c) 1988. Lattice C v5.06 is a trademark or registered trademark of HiSoft and Lattice, Inc. Copyright (c) 1990-91. Sozobon C version made possible with the use of: Ian Lepore's .......GEMFAST VDI & AES Library David W. Brooks' ...Floating Point Library for Sozobon C __________________________________________________________________ Purpose __________________________________________________________________ Do you have any Turbo C code that you'd like to run on your ST/STe/TT, but it uses the graphics library? Would you like to be able to display graphics without exploring GEM's VDI functions? If you said "Yes!!!" to either of these questions, then my graphics library is for you. This is a graphics library for Lattice C v5.06, Sozobon C v2.0 and Ian Lepore's Heat & Serve Sozobon C compilers that provides graphic functions without having to delve into the VDI functions of GEM. Rather than come up with my own graphic function names, I used the same names as in Turbo C v2.0 and provided the same functionality. This way the C code you write on your ST/STe/TT can be easily ported to the PC and compiled with Turbo C with little or no modification. And of course, porting Turbo C code to your ST/STe/TT will be much easier. Although the library is not 100% compatible with Turbo C's library, it still provides a valuable starting point in the task of porting graphic intensive Turbo C code between the ST/STe/TT and PC. Of the 93 graphics functions in Turbo C v2.0, not all have been implemented. Functions not implemented are still documented and have an brief explanation of why it is not provided. If the library doesn't provide all the functionality desired it is because I didn't think it was a widely used function or it was not applicable to the ST or I didn't have the technical information to implement it. Feel free to send any comments or suggestions you have for improving the library. My mailing address and e-mail address are on the title page. I'm not sure how long I'll have the Internet address, but it won't hurt to try Internet. __________________________________________________________________ FREEWARE Notice __________________________________________________________________ I had originally started building the graphics library for my own use since I had a lot of Turbo C code around that would be useful on my MEGA ST2. So I created this library to help port the source code to my MEGA ST2. I found the graphics library so useful that I thought others would be interested and decided to refine the library and include some detailed documentation. Graphics Library v1.1 is provide as FREEWARE!! You should not have paid money, with the exception of media cost, for this graphics library. Graphics Library v1.1 can be distributed and used free of charge and may NOT be sold, or used in, or distributed with, a commercial product without prior written consent from me. __________________________________________________________________ Disclaimer __________________________________________________________________ Although I've tested the library on my existing Turbo C code and written numerous testcases that exercised all the functions, I can't guarantee that this graphics library is bug free. Therefore: Graphics Library v1.1 is provided AS IS. I make no warranties, either expressed or implied, with respect to the software, documentation, its level of compatibility, quality, performance, or fitness. I will not be liable for direct, indirect, or consequential damages resulting from any defects in or misuse of the software. Having said that, I hope you find Graphics Library v1.1 as useful as I do. __________________________________________________________________ Manifest __________________________________________________________________ The archive file graphx11.zoo contains several files in directories as follows: bgidemo\ bgidemo.prg Turbo C's BGI demo program compiled with Lattice C v5.0 and Graphics Library v1.1. It can be run in all resolutions. demos\ lines.c a small demo program that produces a Qix like object on the screen. This file can be compiled by Lattice, Sozobon and Turbo C. sort.c a small demo program that sorts a list of random number using shell, insertion, selection and quick sort methods. The process of sorting is shown graphically. This file can be compiled by Lattice, Sozobon and Turbo C. docs\ graphx11.doc a 1ST Word Plus document file containing the graphics library manual. graphx11.txt a pure ASCII version of the above. This is provided so the manual can be printed with your favourite hardcopy utility. lc_lib\ graphics.lib the Lattice C object module library file, built with Lattice's oml.ttp, that must be linked with your object files. graphics.hdr a compressed graphics header file used by Lattice C and created using Lattice's lcompact.ttp utility provided with Lattice C. graphics.hlc the graphics library header file used by Lattice C in pure ASCII. soz_lib\ graphics.a the Heat & Serve Sozobon C v1.33i and Sozobon C v2.0 object module library file, built with ar.ttp, that must be linked with your object files. graphics.hsz the graphics library header file used by Sozobon C and Heat & Serve Sozobon C. extras\ gemfst17.lzh Sozobon C v2.0 users will have to install Ian Lepore's GEMFAST VDI & AES libraries before my graphics library can be used. If using Heat & Serve Sozobon C v1.33i you already have this library. fplib10b.arc Sozobon C v2.0 users will have to install David W. Brooks' replacement floating point library before my graphics library can be used. If using Heat & Serve Sozobon C v1.33i you don't need this libray. If any of these files are missing, the original graphx11.zoo file has been tampered with. Please locate a complete graphx11.zoo file. If you give a copy to someone else, please distribute the complete archive and not bits and pieces. Thanks. __________________________________________________________________ Installation __________________________________________________________________ The installation procedure is really quite simple. There are two ways that the graphics library can be utilized by your C compiler. You can place the files in the appropriate directories used by C your compiler or simply copy them to your working directory where your C source code resides. Personally, I prefer the files to be in the compiler's directories so you don't have to copy the files all over the place before using it. Installation for Lattice C v5.06 From lc_lib\ of graphx11.zoo 1) copy graphics.lib to \lc\lib\graphics.lib 2) copy graphics.hlc to \lc\headers\graphics.h 3) copy graphics.hdr to \lc\h\graphics.h Installation for Sozobon C v2.0 From soz_lib\ of graphx11.zoo 1) copy graphics.a to \sozo_20\lib\graphics.a 2) copy graphics.hsz to \sozo_20\include\graphics.h 3) Install the GEMFAST libraries as outlined in the GEMFAST documentation. 4) Install the replacement floating point libraries as outlined in the documentation. Installation for Heat & Serve Sozobon C v1.33i From soz_lib\ of graphx11.zoo 1) copy graphics.a to \sozo_133i\lib\graphics.a 2) copy graphics.hsz to \sozo_133i\include\graphics.h Please ensure that the correct object file is copied into the \lib directory because they are not interchangeable. The graphics.lib file is a Lattice C specific object module library file and the graphics.a file is a DRI object module library file used by Sozobon C. __________________________________________________________________ Using the Graphics Library __________________________________________________________________ To use the graphics library, all one must do is place the appropriate #include statement in your C code source code that will use graphic functions. If you have installed the graphics library in the C compiler's directories then simply insert the #include <graphics.h> statement in your source file. If however, you decided not to install the graphics library in the compiler's directories, then use #include "graphics.h" (note the double quotes). This causes the preprocessor to look in the current directory for the header file. If not found, the compiler's directory (\lc\h or \sozobon\include) is searched. Sozobon C users please note: Due to a problem I encountered when creating the library for Sozobon C, you will also have to add a #define to your source file. #define __MAIN_SRC__ must be placed in the source file, before #include <graphics.h>, that contains the main() function. This is necessary so that the four functions in the header file are compiled with your source code. For some strange reason these functions cause a system crash included in graphics.a. I tried several ways to overcome this problem and this is the solution I came up with. It seems a bit messy, but it works fine. I'll try to find a solution to this problem. Lattice C users please note: The graphics.h file defines enumerated types that contain duplicate values. Lattice C generates warning #79 when duplicate values are encountered in enumerated types. To eliminate these messages simply include the argument -j79i when using lc.ttp, as shown below, or add it to the LC_OPT environment variable. Once your source code has been compiled into object files, the graphics library must be linked with your object files as follows: Compiling and linking with Lattice C 1) lc.ttp -fm -j79i myprog.c 2) clink c.o+myprog.o LIB graphics.lib+lcm.lib+lcg.lib+lc.lib TO myprog.prg 3) run myprog.prg Compiling and linking with Sozobon C v2.0 1) cc -o myprog.prg -r myprog.c graphics.a vdifast.a aesfast.a 2) run myprog.prg Compiling and linking with Heat & Server Sozobon C v1.33i 1) cc -o myprog.prg myprog.c graphics.a libm.a vdifast.a aesfast.a 2) run myprog.prg If you decide to freely distribute a program of yours that was created with the help of this library how about mentioning Kenneth W. Hartlen, Ian Lepore and David W. Brooks in the credits. We aren't receiving any money for our efforts so it would be nice to at least see our names in lights! Thanks. ** WARNING!! ** If programs are aborted before closegraph() is called unpredicable results will occur when you tried to run another program. Make sure that a closegraph() is performed before the program ends otherwise you should re-boot your system. __________________________________________________________________ Future Enhancements __________________________________________________________________ At the moment this graphics library suits my needs quite well. I was able to compile and run all my Turbo C v2.0 graphics code, written while in university, on my MEGA ST2! The only real deviation from Turbo C is the font capability with the installuserfont function. This graphics library simply uses variations of the system font using settextstyle rather than loading different type faces. I had considered allowing the use of GDOS, but I'm unsure if it is really necessary and it would limit the use of the library. If you'd like to see something added, or changed, to enhance compatiblity with Turbo C's graphics library just let me know. __________________________________________________________________ What's Changed? __________________________________________________________________ July 16/92 Version 1.0: Unleashed Graphics Library on the masses. August 6/92 Version 1.1: #defines were added to graphics.hsz to prevent 'double define' during linking. This problem was encountered when M.A. Rahin attempted to use the library with Heat & Serve Sozobon C v1.33i. Turbo C's graphic functions have very long names and when truncated to 8 characters caused some duplicate function names. For example, settextjustify and settextstyle truncated to _settext. Some internal variables were also renamed to avoid the 'double define'. __________________________________________________________________ The Graphic Functions __________________________________________________________________ As mentioned earlier, the graphics library is Turbo C v2.0 compatible, but not 100% compatible and some minor variations exist. Aside: For those familiar with Turbo C, I had the BGIDEMO.C file compiled and running with Lattice C in less than an hour! Only minor modifications using #ifdefs were needed to the 45K source file so it could be compiled in Lattice or Turbo C! What follows is a complete description of each graphic function available in the library. Functions not implemented will still have a brief description and a reason why it was not implemented. If you don't agree with my reasoning, let me know why and I'll see what I can do about implementing it in a future release. __________________________________________________________________ arc Draws a circular arc __________________________________________________________________ Syntax void far arc(int x,int y,int stangle,int endangle, int radius); Purpose arc draws an arc at (x,y) with the given radius. The arc is drawn from stangle to endangle. If stangle equals endangle a complete circle is drawn. stangle and endangle are angles measured in degrees going counterclockwise, with 0 degrees being at 3 o'clock, 90 degrees at 12 o'clock, and so on. The arc is drawn in the current colour, line style and thickness. __________________________________________________________________ bar Draws a two-dimensional bar __________________________________________________________________ Syntax void far bar(int left, int top, int right, int bottom); Purpose bar draws a filled-in rectangular, two-dimensional bar using the current fill style and fill colour. The bar is not outlined, an outlined bar can be drawn using the bar3D functions with a depth of zero. The upper left corner is defined by (left,top) and the lower right corner by (right,bottom). __________________________________________________________________ bar3d Draws a 3-D bar __________________________________________________________________ Syntax void far bar3d(int left, int top, int right, int bottom, int depth, int topflag); Purpose bar3d draws a three-dimensional rectangular bar using the current fill style and fill colour, then outlines it with the current colour, line style and thickness. The 3D effect is governed by depth and if the topflag is nonzero, the 3D bar with be drawn with a top. The upper left corner is defined by (left,top) and the lower right corner by (right,bottom). __________________________________________________________________ circle Draws a circle __________________________________________________________________ Syntax void circle(int x, int y, int radius); Purpose circle draws a circle using the current colour, line style and thickness at (x,y) with a radius given by radius. The circle drawn will be a true circle in any resolution, unlike the PC where the aspect ratio has to be adjusted appropriately. __________________________________________________________________ cleardevice Clears the graphics screen __________________________________________________________________ Syntax void far cleardevice(void); Purpose cleardevice erases the entire graphics screen and sets the current position (CP) to (0,0). __________________________________________________________________ clearviewport Clears the current viewport __________________________________________________________________ Syntax void far clearviewport(void); Purpose clearviewport erases the viewport and sets current position (CP) to (0,0) relative to the viewport. __________________________________________________________________ closegraph Shuts down the graphics system __________________________________________________________________ Syntax void far closegraph(void); Purpose closegraph restores the original colour palette, and clears the screen. __________________________________________________________________ detectgraph Determines graphics driver and mode to use by checking the hardware __________________________________________________________________ Syntax void far detectgraph(int far *graphdriver, int far *graphmode); Purpose detectgraph returns the monitor type in graphdriver and the graphics mode in graphmode which indicates the highest resolution possible. If no graphics hardware is detected, *graphdriver is set to grNotDetected and graphresult will return grNotDetected. *graphdriver is an integer that indicates the driver to be used. You can use constants defined by the graphics_driver enumeration type as shown below. graphics_driver constant Numeric value -------------------------------------- DETECT 0 (autodetection) ... .. (CGA, EGA, VGA, etc) SC1224 11 SM124 12 TTC1432 13 TTM194 14 UNKNOWN_DRIVER 15 *graphmode is an integer that indicates the screen mode to be used. You can use constants defined by the graphics_mode enumeration type as shown below. graphics_mode constant Numeric value -------------------------------------- CGAC0 0 ... .. (CGA, EGA, VGA, etc) SC1224LO 0 SC1224MED 1 SM124HI 0 TTC1434LO 0 TTC1434MED 1 TTM194HI 1 UNKNOWN_MODE 0 __________________________________________________________________ drawpoly Draws the outline of a polygon __________________________________________________________________ Syntax void far drawpoly(int numpoints, int far *polypoints); Purpose drawpoly draws a polygon having numpoints points using the current colour, line style and thickness. polypoints series of numpoints x 2 integers defining the vertices for the polygon. Each pair of integers represents an (x,y) coordinate of a vertex. In order to draw an enclosed polygon having n vertices you must use pass n + 1 coordinates, where the nth coordinate equals the 0th. graphresult will return grNoScanMem if an error occurs drawing the polygon. __________________________________________________________________ ellipse Draws an elliptical arc __________________________________________________________________ Syntax void far ellipse(int x, int y, int stangle, int endangle, int xradius, int yradius); Purpose ellipse draws an elliptical arc centered at (x,y) with a horizontal and vertical radii given by xradius and yradius using the current colour, line style and thickness. The ellipse is drawn from stangle to endangle. If stangle equals endangle a complete ellipse is drawn. stangle and endangle are angles measured in degrees going counterclockwise, with 0 degrees being at 3 o'clock, 90 degrees at 12 o'clock, and so on. __________________________________________________________________ fillellipse Draws and fills an ellipse __________________________________________________________________ Syntax void far fillellipse(int x, int y, int xradius, int yradius); Purpose fillellipse draws an ellipse centered at (x,y) with a horizontal and vertical radii given by xradius and yradius. The ellipse is filled with the current fill style and colour, then outlined with the current colour, line style and thickness. __________________________________________________________________ fillpoly Draw and fill a polygon __________________________________________________________________ Syntax void far fillpoly(int numpoints, int far *polypoints); Purpose fillpoly draws a polygon having numpoints points, fills it with the current fill style and colour and outlines it using the current colour, line style and thickness. polypoints is series of numpoints x 2 integers defining the vertices for the polygon. Each pair of integers represents an (x,y) coordinate of a vertex. Unlike drawpoly, only n vertices are needed and fillpoly takes care of creating an additional vertex to close the polygon. graphresult will return grNoScanMem if an error occurs drawing the polygon. __________________________________________________________________ floodfill Flood-fills a bounded region __________________________________________________________________ Syntax void far floodfill(int x, int y, int border); Purpose floodfill fills a bounded region on the screen starting from (x,y). The bounded region is defined by the colour specified by border. The region is filled with the current fill style and colour. __________________________________________________________________ getarccoords Gets coordinates of the last call to arc __________________________________________________________________ Syntax void far getarccoords(struct arccoordstype far *arccoords); Purpose getarccoords fills in the arccoordstype structure pointed to by arccoords with the information about the last call to arc. arccoordstype is defined in graphics.h and has the following structure: struct arccoordstype { int x, y; int xstart, ystart, xend, yend; }; This information is especially useful if want a line to meet at the end of the arc or to connect the endpoints of the arc with a straight line. __________________________________________________________________ getaspectratio Retrieves the current graphic mode's aspect ratio __________________________________________________________________ Syntax void far getaspectratio(int far *xasp, int far *yasp); Purpose getaspectratio places the width of a screen pixel in xasp and the height of a screen pixel in yasp. Using these values you can calculate the screen's aspect ratio by xasp/yasp. The aspect ratio can then be used to draw true squares in any resolution. graphics_mode xasp yasp ---------------------------------- SC1224LO 338 372 SC1224MED 169 372 SM124HI 372 372 TTC1434LO ??? ??? TTC1434MED ??? ??? TTM194HI ??? ??? __________________________________________________________________ getbkcolor Returns the current background colour __________________________________________________________________ Syntax int far getbkcolor(void); Purpose getbkcolor returns the current background colour of the screen. (See setbkcolor for more information.) __________________________________________________________________ getcolor Returns the current drawing colour __________________________________________________________________ Syntax int far getcolor(void); Purpose getcolor return the current line drawing colour. __________________________________________________________________ getdefaultpalette Returns the palette definition structure __________________________________________________________________ Syntax struct palettetype *far getdefaultpalette(void); Purpose getdefaultpalette returns a pointer to palettetype structure that contains the default colours. __________________________________________________________________ getdrivername Returns a pointer to a string containing the name of the current graphics driver __________________________________________________________________ Syntax char *far getdrivername(void); Purpose getdrivername returns a pointer to a string that contains the name of the graphics driver being used. __________________________________________________________________ getfillpattern Copies a user-defined fill pattern into memory __________________________________________________________________ Syntax void far getfillpattern(char far *pattern); Purpose getfillpattern copies the currently used fill pattern into memory pointed to by pattern. pattern points to a sequence of 8 bytes with each byte defining the pattern for a line in the pattern. A 1 bit indicates which pixels are to be drawn. byte # char contents pattern to draw --------------------------------------------- 0 0xF0 1 1 1 1 0 0 0 0 1 0x8E 1 0 0 0 1 1 1 0 2 0xF4 1 1 1 1 0 1 0 0 3 0x14 0 0 0 1 0 1 0 0 4 0xF4 1 1 1 1 0 1 0 0 5 0x04 0 0 0 0 0 1 0 0 6 0x04 0 0 0 0 0 1 0 0 7 0x00 0 0 0 0 0 0 0 0 __________________________________________________________________ getfillsettings Gets information about the current fill pattern and colour __________________________________________________________________ Syntax void far getfillsettings(struct fillsettingstype far *fillinfo); Purpose getfillsettings fills in the fillsettingstype structure pointed to by fillinfo with the information about the current fill style and colour. fillsettingstype is defined in graphics.h and has the following structure: struct fillsettingstype { int pattern; int color; }; There are 39 fill patterns available for use. Some are predefined in the enumerated type fill_patterns and correspond as closely as possible with Turbo C. fill_patterns Numeric constant value -------------------------------------------------- EMPTY_FILL 0 fills with background colour SOLID_FILL 1 fills with fill colour LINE_FILL 2 --- fill LTSLASH_FILL 3 /// fill SLASH_FILL 4 /// fill with thick lines BKSLASH_FILL 5 \\\ fill with thick lines LTBKSLASH_FILL 6 \\\ fill HATCH_FILL 7 light hatch fill XHATCH_FILL 8 heavy cross hatch fill INTERLEAVE_FILL 9 interleaving line fill WIDE_DOT_FILL 10 widely spaced dot fill CLOSE_DOT_FILL 11 closely spaced dot fill USER_FILL 12 use user defined fill __________________________________________________________________ getgraphmode Returns the current graphics mode __________________________________________________________________ Syntax int far getgraphmode(void); Purpose getgraphmode returns the current graphics mode. Names for the values are defined in graphics.h in the enumeration type graph_modes. __________________________________________________________________ getimage Saves a bit image of the specified region into memory __________________________________________________________________ Syntax void far getimage(int left, int top, int right, int bottom, void far *bitmap); Purpose getimage saves a rectangular portion of the screen, defined by (left,top) to (right,bottom), to memory pointed to by bitmap. This function is particularly useful in combination which putimage to animate something on the screen. __________________________________________________________________ getlinesettings Gets the current line style, pattern and thickness __________________________________________________________________ Syntax void far getlinesettings(struct linesettingstype far *lineinfo); Purpose getlinesettings fills in the linesettingstype structure pointed to by lineinfo with the information about the current line style, user defined pattern and thickness. linesettingstype is defined in graphics.h and has the following structure: struct linesettingstype { int linestyle; unsigned upattern; int thickness; }; The line styles names are predefined in the enumerated type line_styles and correspond as closely as possible with Turbo C. line_styles Numeric constant value ----------------------- SOLID_LINE 0 DOTTED_LINE 1 CENTER_LINE 2 DASHED_LINE 3 USERBIT_LINE 4 __________________________________________________________________ getmaxcolor Returns maximum colour value that can be passed to setcolor __________________________________________________________________ Syntax int far getmaxcolor(void); Purpose getmaxcolor simply returns the highest valid pen number that can be passed to setcolor. The returned values are: 1 for SM124HI, 3 for SC1224MED and 15 for SC1224LO, 255 for TTC1434LO, 15 for TTC1434MED and 2 for TTM194HI. __________________________________________________________________ getmaxmode Returns the maximum mode number for the current driver __________________________________________________________________ Syntax int far getmaxmode(void); Purpose getmaxmode returns the maximum mode number for the current driver. __________________________________________________________________ getmaxx Returns maximum x screen coordinate __________________________________________________________________ Syntax int far getmaxx(void); Purpose getmaxx returns the maximum x coordinate for the current graphics mode. For example, the resolution for SM124HI is 640x400 so getmaxx returns 639. __________________________________________________________________ getmaxy Returns maximum y screen coordinate __________________________________________________________________ Syntax int far getmaxy(void); Purpose getmaxy returns the maximum y coordinate for the current graphics mode. For example, the resolution for SM124HI is 640x400 so getmaxy returns 399. __________________________________________________________________ getmodename Returns a pointer to a string containing the name of a specified graphics mode __________________________________________________________________ Syntax char *far getmodename(int mode_number); Purpose getmodename returns a pointer to a string that contains the name, specified by mode_number, of the graphics mode being used. __________________________________________________________________ getmoderange Gets the range of modes for a given graphics driver __________________________________________________________________ Syntax void far getmoderange(int graphdriver, int far *lomode, int far *himode); Purpose getmoderange returns the range of valid modes for the specified driver. If graphdriver is invalid then *lomode and *himode are set to -1. If graphdriver is -1 then the current mode is returned in *lomode and *himode. __________________________________________________________________ getpalette Gets information about the current palette __________________________________________________________________ Syntax void far getpalette(struct palettetype far *palette); Purpose getpalette fills in the palettetype structure pointed to by palette with the information about the current colour palette being used. palettetype is defined in graphics.h and has the following structure: #define MAXCOLORS 15; struct palettetype { unsigned size; char colors[MAXCOLORS+1]; }; size contains the number of entries being used in colors. Each entry in colors stores the color for that drawing pen. __________________________________________________________________ getpalettesize Returns size of palette colour lookup table __________________________________________________________________ Syntax int far getpalettesize(void); Purpose getpalettesize returns the number of palette entries for the current graphics mode. __________________________________________________________________ getpixel Gets the colour of a specified pixel __________________________________________________________________ Syntax unsigned far getpixel(int x, int y); Purpose getpixel returns the pen number that was used to draw the pixel on the screen at the (x,y) coordinate. __________________________________________________________________ gettextsettings Gets information about the current graphics text font __________________________________________________________________ Syntax void far gettextsettings(struct textsettingstype far *texttypeinfo); Purpose gettextinfo fills in the textsettingstype structure pointed to by texttypeinfo with the information about the current text font, direction, size, effects and justification. textsettingstype is defined in graphics.h and has the following structure: struct textsettingstype { int font; int direction; int charsize; int horiz; int vert; }; __________________________________________________________________ getviewportsettings Gets information about the current viewport __________________________________________________________________ Syntax void far getviewsettings(struct viewporttype far *viewport); Purpose getviewportsettings fills in the viewporttype structure pointed to by viewport with the information about the current viewport. viewporttype is defined in graphics.h and has the following structure: struct viewporttype { int left, top, right, bottom; int clip; }; __________________________________________________________________ getx Returns the current graphics position's x coordinate __________________________________________________________________ Syntax int far getx(void); Purpose getx returns the current position's (CP) x coordinate. This value is viewport relative. __________________________________________________________________ gety Returns the current graphics position's y coordinate __________________________________________________________________ Syntax int far gety(void); Purpose gety returns the current position's (CP) y coordinate. This value is viewport relative. __________________________________________________________________ graphdefaults Resets all graphics settings to their defaults __________________________________________________________________ Syntax void far graphdefaults(void); Purpose graphdefault resets all graphics settings the appropriate defaults: sets default palette colours and drawing colour. sets default fill style and colour. sets default line style. sets default text style and justification. sets viewport to entire screen with clipping on. __________________________________________________________________ grapherrormsg Returns a pointer to an error message string __________________________________________________________________ Syntax char * far grapherrormsg(int errorcode); Purpose grapherrormsg returns a pointer to the error message text associated with errorcode value returned by graphresult. __________________________________________________________________ _graphfreemem User hook into graphics memory allocation __________________________________________________________________ Syntax void far _graphfreemem(void far *ptr, unsigned size); Purpose _graphfreemem is a memory management routine used by Turbo C to free allocated graphics memory and has not be implemented on the ST/STe/TT. After a call to _graphfreemem, graphresult will return grNotImplemented. __________________________________________________________________ _graphgetmem User hook into graphics memory allocation __________________________________________________________________ Syntax void far _graphgetmem(unsigned size); Purpose _graphgetmem is a memory management routine used by Turbo C to allocate graphics memory and has not be implemented on the ST/STe/TT. After a call to _graphgetmem, graphresult will return grNotImplemented. __________________________________________________________________ graphresult Returns an error code for the last unsuccessful graphics operation __________________________________________________________________ Syntax int far graphresult(void); Purpose graphresult returns the error code that was reported for the last graphics operation. The error status is reset to grOk. All graphics functions will set the error status to grOk unless something has gone wrong. Error graphics_errors code constant message string ------------------------------------------------------- 0 grOk No error -1 grNoInit GraphGraphics not initia- lized (use 'initgraph') -2 grNotDetected Graphics hardware not de- tected -3 grFileNotFound Device driver file not fo- und -4 grInvalidDriver Invalid device driver file -5 grNoLoadMem Not enough memory to load driver -6 grNoScanMem Out of memory in scan fill -7 grNoFloodMem Out of memory in flood fill -8 grFontNotFound Font file not found -9 grNoFontMem Not enough memory to load font -10 grInvalidMode Invalid graphics mode for selected driver -11 grError Graphics error -12 grIOerror Graphics I/O error -13 grInvalidFont Invalid font file -14 grInvalidFontNum Invalid font number -15 grInvalidDeviceNum Invalid device number -16 grInvalidFontSize Invalid font size -17 grNotImplemented Not implemented on Atari ST/STe/TT -18 grInvalidVersion Invalid version number __________________________________________________________________ imagesize Returns the number of bytes required to store a bit image __________________________________________________________________ Syntax unsigned far imagesize(int left, int top, int right, int bottom); Purpose imagesize determines the number of bytes of memory required to store a bit image. __________________________________________________________________ initgraph Initializes the graphics system __________________________________________________________________ Syntax void far initgraph(int far *graphdriver, int far *graphmode, char far *pathtodriver); Purpose initgraph initializations the graphics system and must be called before any graphics functions are attempted. If a graphic function is called before initgraph an error message will be displayed and the program will terminate. *graphdriver is an integer that indicates the driver to be used. You can use constants defined by the graphics_driver enumeration type as shown below. graphics_driver constant Numeric value -------------------------------------- DETECT 0 (autodetection) ... .. (CGA, EGA, VGA, etc) SC1224 11 SM124 12 TTC1434 13 TTM194 14 UNKNOWN_DRIVER 15 *graphmode is an integer that indicates the screen mode to be used. You can use constants defined by the graphics_mode enumeration type as shown below. graphics_mode constant Numeric value -------------------------------------- CGAC0 0 ... .. (CGA, EGA, VGA, etc) SC1224LO 0 SC1224MED 1 SM124HI 0 TTC1434LO 0 TTC1434MED 1 TTM194HI 0 UNKNOWN_MODE 0 Note: Refer to graphics.h for a complete list of values. Only ST/STe/TT specific values are used. After initgraph is called, graphdriver and graphmode will be updated to the appropriate values to indicated the actual graphics mode set. pathtodriver has no effect on the ST/STe/TT since graphic drivers cannot be loaded. If no graphics hardware is detected, *graphdriver is set to grNotDetected and graphresult will also return grNotDetected. __________________________________________________________________ installuserdriver Installs a vendor-added device driver to the BGI device driver table __________________________________________________________________ Syntax int far installuserdriver(char far *name, int huge (*detect)(void)); Purpose installuserdriver is used to load alternative graphics drivers and has not be implemented on the ST/STe/TT. After a call to _graphgetmem, graphresult will return grNotImplemented. __________________________________________________________________ installuserfont Loads a font file that is not built into the BGI system __________________________________________________________________ Syntax int far installuserfont(char far *name); Purpose installuserfont is used to load a "stroked" font and has not been implemented on the ST/STe/TT. After a call to installuserfont, graphresult will return grNotImplemented. __________________________________________________________________ line Draws a line between two specified points __________________________________________________________________ Syntax void far line(int x1, int y1, int x2, int y2); Purpose line draws a line using the current colour, line style, thickness between the (x1,y1) and (x2,y2) points. __________________________________________________________________ linerel Draws a line a relative distance from the current position (CP) __________________________________________________________________ Syntax void far linerel(int dx, int dy); Purpose linerel draws a line from the current position (CP) to the point (dx,dy) which is a relative distance from CP. CP is adjusted by (dx,dy).The current colour, line style and thickness are used. __________________________________________________________________ lineto Draws a line from the current position (CP) to (x,y) __________________________________________________________________ Syntax void far lineto(int x, int y); Purpose lineto draws a line from the current position (CP) to the point (x,y). CP is moved to (x,y). The current colour, line style and thickness are used. __________________________________________________________________ moverel Moves the current position (CP) a relative distance __________________________________________________________________ Syntax void far moverel(int dx, int dy); Purpose moverel moves the current position (CP) by dx in the horizontal direction and dy in the vertical direction. __________________________________________________________________ moveto Moves the current position (CP) to (x,y) __________________________________________________________________ Syntax void far moveto(int x, int y); Purpose moveto moves the current position (CP) to the point specified by (x,y). __________________________________________________________________ outtext Displays a string in the viewport __________________________________________________________________ Syntax void far outtext(char far *textstring); Purpose outtext displays a text string in the viewport using the current text style, size, justification and direction. outtext displays textstring at the current position (CP). If the horizontal justification is set to LEFT_TEXT and the vertical justification to HORIZ_TEXT, then CP's x coordinate is adjusted by textwidth(textstring). Otherwise CP is unchanged. __________________________________________________________________ outtextxy Displays a string at a specified location __________________________________________________________________ Syntax void far outtextxy(int x, int y, char far *textstring); Purpose outtextxy displays a text string in the viewport using the current text style, size, justification and direction at (x,y). The current position (CP) is not changed. __________________________________________________________________ pieslice Draws and fills in pie slice __________________________________________________________________ Syntax void far pieslice(int x, int y, int stangle, int endangle, int radius); Purpose pieslice draws a pieslice at (x,y) with a radius given by radius. The pieslice is drawn from the stangle to the endangle. stangle and endangle are given in degrees and measured counterclockwise with 0 degrees being at 3 o'clock. The pieslice is filled with the current fill style and colour, then outlined with the current colour, line style and thickness. __________________________________________________________________ putimage Outputs a bit image onto the screen __________________________________________________________________ Syntax void far putimage(int left, int top, void far *bitmap, int op); Purpose putimage draws the bit image saved by getimage on the screen with the upper right corner being positioned at (left,top). bitmap points to the location in memory where the image is stored. op indicates who the image is to be drawn on the screen. The enumeration type putimage_ops, as found in graphics.h, gives name for the op values. putimage_ops constant value description ----------------------------------------- COPY_PUT 0 copy XOR_PUT 1 exclusive or OR_PUT 2 inclusive or AND_PUT 3 and NOT_PUT 4 copy the inverse __________________________________________________________________ putpixel Plots a pixel at a specific point __________________________________________________________________ Syntax void far putpixel(int x, int y, int color); Purpose putpixel draws a single point at (x,y) using the given color. __________________________________________________________________ rectangle Draws a rectangle __________________________________________________________________ Syntax void far rectangle(int left, int top, int right, int bottom); Purpose rectangle draws a rectangle from the upper left corner (left,top) to the lower right corner (right,bottom) using the current colour, line style and thickness. __________________________________________________________________ registerbgidriver and registerfarbgidriver Registers a user-loaded or linked-in graphics driver code with the graphics system __________________________________________________________________ Syntax int registerbgidriver(void (*driver)(void)); int registerfarbgidriver(void (*driver)(void)); Purpose registerbgidriver and registerfarbgidriver have not been implemented in this graphics library. graphresult will report a grNotImplemented error. __________________________________________________________________ registerbgifont and registerfarbgifont Registers a user-loaded or linked-in graphics font code with the graphics system __________________________________________________________________ Syntax int registerbgifont(void (*font)(void)); int registerfarbgifont(void (*font)(void)); Purpose registerbgifont and registerfarbgifont have not been implemented in this graphics library. graphresult will report a grNotImplemented error. __________________________________________________________________ restorecrtmode Restores the screen mode to its pre-initgraph setting __________________________________________________________________ Syntax void far restorecrtmode(void); Purpose restorecrtmode returns the screen to text mode. The screen is cleared and the cursor returns to the home position (0,0). This function can be used in conjuction with setgraphmode to switch between text and graphic modes. __________________________________________________________________ sector Draw and fills an elliptical pie slice __________________________________________________________________ Syntax void far sector(int x, int y, int stangle, int endangle, int xradius, int yradius ); Purpose sector draws an elliptical pieslice located at (x,y) with a horizontal radius of xradius and a vertical radius of yradius. The sector is drawn from stangle and ends at endangle. The sector is filled with the current fill style and colour, then outlined with the current line colour, style and thickness. stangle and endangle are given in degrees. The angle is measured counterclockwise with 0 degrees being at 3 o'clock. __________________________________________________________________ setactivepage Sets active page for graphics output __________________________________________________________________ Syntax void far setactivepage(int page); Purpose setactivepage has no effect on the ST/STe/TT implementation since only ONE page is used. If page is non-zero graphresult returns grError. __________________________________________________________________ setallpalette Changes all palette colours as specified __________________________________________________________________ Syntax void far setallpalette(struct palettetype far *palette); Purpose setallpalette sets the colour palette to the colour values contained in the palettetype structure pointed to by palette. palettetype as the following structure define in graphics.h. #define MAXCOLORS 15 struct palettetype { unsigned char size; signed char colors[MAXCOLORS+1]; }; size indicates how many entries in the colors array exist. colors holds the color numbers. __________________________________________________________________ setaspectratio Changes the default aspect ratio correction factor __________________________________________________________________ Syntax void far setaspectratio(int xasp, int yasp); Purpose setaspectratio has not been implemented since the VDI routines correctly handle the aspect ratio. The purpose of setaspectratio for the PC is to correct the aspect ratio for add on graphics drivers. graphresult will return grNotImplemented if setaspectratio is called. __________________________________________________________________ setbkcolor Sets the current background colour using the palette __________________________________________________________________ Syntax void far setbkcolor(int color); Purpose setbkcolor sets the background color (pen 0) to color. Number Colour ------------------------ 0 BLACK 1 BLUE 2 GREEN 3 CYAN 4 RED 5 MAGENTA 6 BROWN 7 LIGHTGRAY 8 DARKGRAY 9 LIGHTBLUE 10 LIGHTGREEN 11 LIGHTCYAN 12 LIGHTRED 13 LIGHTMAGENTA 14 YELLOW 15 WHITE __________________________________________________________________ setcolor Sets the current drawing colour using the palette __________________________________________________________________ Syntax void far setcolor(int color); Purpose setcolor sets the current drawing colour to color. color can range from 0 to getmaxcolor. See setbkcolor. setcolor also effects the colour of graphic text drawn on the screen. __________________________________________________________________ setfillpattern Selects a user-defined fill pattern __________________________________________________________________ Syntax void far setfillpattern(char far *upattern, int color); Purpose setfillpattern allows the programmer to define user defined fill patterns that will be used by graphic functions that fill shapes. The pattern is defined with 8 bytes, pointed to by upattern, each byte represents the bit pattern per row. See getfillpattern for more information. The fill colour is set to color. __________________________________________________________________ setfillstyle Sets the fill pattern and colour __________________________________________________________________ Syntax void far setfillstyle(int pattern, int color); Purpose setfillstyle sets the fill pattern to pattern, one of the predefined fill patterns and sets the fill colour to color. See getfillsettings for more information. Do not use a pattern of USER_FILL with setfillstyle, use setfillpattern to define and use a user defined fill pattern __________________________________________________________________ setgraphbufsize Changes the size of the internal graphics buffer __________________________________________________________________ Syntax unsigned far setgraphbufsize(unsigned bufsize); Purpose setgraphbufsize has not been implemented in this graphics library. graphresult will report a grNotImplemented error. __________________________________________________________________ setgraphmode Sets the system to graphics mode, clears the screen __________________________________________________________________ Syntax void far setgraphmode(int mode); Purpose setgraphmode returns the screen to graphics mode and resets all graphics settings to their default values. This function can be used in conjuction with restorecrtmode to switch between text and graphic modes. __________________________________________________________________ setlinestyle Sets the current line width and style __________________________________________________________________ Syntax void far setlinestyle(int linestyle, unsigned upattern, int thickness); Purpose setlinestyle sets the current line style to linestyle and thickness to thickness. See getlinesettings for more information about linestyle values. A user-defined line style can also be specified by requesting a USERBIT_LINE in as linestyle and specifying the bit pattern in upattern. If a user defined pattern is not wanted, upattern must still be provided, but is simply ignored. Note: the linestyle setting is only effect when the thickness is 1. __________________________________________________________________ setpalette Changes one palette colour __________________________________________________________________ Syntax void far setpalette(int colornum, int color); Purpose setpalette is not implemented since setrgbpalette will handle all changes to the colour palette. graphresult will return grNotImplemented. __________________________________________________________________ setrgbpalette Allows user to define colour for the IBM8514 __________________________________________________________________ Syntax void far setrgbpalette(int colornum, int red, int green, int blue); Purpose setrgbpalette sets the colornum entry in the colour palette to the red, green, blue values. On the ST/STe these values can range from 0 to 7 and 0 to 15 on the TT. The TT and third party graphic cards are capable of more than 16 colours on the screen. setrgbpalette can change any of them and the first sixteen entries in the palette are set to the default Turbo C colours shown in setbkcolor. __________________________________________________________________ settextjustify Sets text justification for graphics functions __________________________________________________________________ Syntax void far settextjustify(int horiz, int vert); Purpose settextjustify determines how text is displayed with reference to the current position (CP). text_just constant value --------------------- LEFT_TEXT 0 CENTER_TEXT 1 RIGHT_TEXT 2 BOTTOM_TEXT 0 CENTER_TEXT 1 TOP_TEXT 2 __________________________________________________________________ settextstyle Sets the current text characteristics for graphic output __________________________________________________________________ Syntax void far settextstyle(int font, int direction, int charsize); Purpose settextstyle sets the text font, direction, and charsize that will be used by outtext and outtextxy. font can have several values: value result --------------------- 0x00 sytem font 0x01 bold font 0x02 grayed font 0x04 italicized font 0x08 underlined font 0x10 outlined font These font values can be ANDed together to combine the fonts. For example, if font is 0x14 the font is shown italicized and outlied. charsize differs from Turbo C is that it represents the font point size and not a magnification factor. The system font can be displayed in six sizes: value point size -------------------- 0 8 1 9 2 10 3 16 4 18 5 and up 20 __________________________________________________________________ setusercharsize Allows the user to vary the character width and height for fonts __________________________________________________________________ Syntax void far setusercharsize(int multx, int divx, int multy, int divy); Purpose setusercharsize has not been implemented in this graphics library. graphresult will report a grNotImplemented error. __________________________________________________________________ setviewport Sets the current viewport for graphics output __________________________________________________________________ Syntax void far setviewport(int left, int top, int right, int bottom, int clip); Purpose setviewport defines a portion of the screen that will become the new viewport for graphics output. The upper left corner (left,top) and lower right corner (right,bottom) are given in absolute screen coordinates. The current position (CP) is moved to (0,0) and corresponds to the upper left corner. clip determines whether or not graphic operations are clipped at the viewports perimeter. If clip is nonzero, all graphic operations will be clipped. Note: all graphic operations are viewport relative. When setviewport is used, (0,0) will move to the upper left corner (left,top) of the new viewport. __________________________________________________________________ setvisualpage Sets the visual graphics page number __________________________________________________________________ Syntax void far setvisualpage(int page); Purpose setvisualpage has no effect on the ST/STe/TT implementation since only ONE page is used. If page is non-zero graphresult returns grError. __________________________________________________________________ setwritemode Sets the writing mode for line drawing __________________________________________________________________ Syntax void far setwritemode(int mode); Purpose setwritemode effects how the output of the graphic functions appears using binary operations. COPY_PUT simply copies the new output to the screen and XOR_PUT performs an exclusive OR operation between the output and the existing screen image. A second XOR_PUT of the same graphic output will erase the result of the first one. __________________________________________________________________ textheight Returns the height of a string in pixels __________________________________________________________________ Syntax int far textheight(char far *textstring); Purpose textheight determines the height of textstring, in pixels, of the current text font. This function is very useful for creating resolution independent programs that use text. Use textheight rather than doing the calculation manually. __________________________________________________________________ textwidth Returns the width of a string in pixels __________________________________________________________________ Syntax int far textwidth(char far *textstring); Purpose textwidth determines the width of textstring, in pixels, of the current text font. This function is very useful for creating resolution independent programs that use text. Use textwidth rather than doing the calculation manually.